Using Tokens in Notifications

Notification messages can be dynamically created using current data in the Point Service, the Current Value Service, or the Facility Service. The identifiers used to create dynamic messages are called "tokens." A token represents a point attribute and can include any property from the point configuration record, the point’s CVS record, or its facility attributes. When the notification is sent, the GNS will replace the token(s) with the appropriate data. Notification messages can also include other points (data values or descriptive information) using a reference point token substitution method.

Tokens and reference points can be used to define a dynamic string of text for both Set and Clear notification messages in the following places:

• subject line of an email or SMS message
• body of an alphanumeric message or email message or SMS message or voice address message
• file path and/or file name of a WAV message file (see example below).

See the following subsections for more information:

• Configure Token Strings
  • To Build a String Using Text Tokens

• Notification Message Example
• Notification Token Categories
• WAV File Example
• Beware of Typographical Errors

Configure Token Strings

Tokens are configured on the Edit <item> token chooser dialog box, which is accessed by clicking the appropriate Browse button on the right of the Messages page of the Notifications Properties dialog box.

The properties on the Edit <item> dialog box are described below.

To Build a String Using Text Tokens

See Using Text Tokens in the CygNet Studio section for general information about using tokens.

1. Show the Edit <item> dialog box by clicking … next to the item for which you want to add a token (Email Subject, Message, or Wav Msg).
2. Clear the text in the Edit Text field.
3. Select a category from the drop-down menu.
4. Select an attribute from the list and click Insert Token to add it to the field. Double-clicking a token will also add it.
5. Repeat to add more tokens, as desired.
6. Type in the Edit Text field to add static text, spaces between tokens, parentheses, and other punctuation.
7. To include a reference tag to a point other than the point triggering the notification, add a desired token, click inside the token, then select Reference Tag to open the Reference Tag dialog box. See Including Other Points in Notifications.
8. To format a token, click inside the token’s closing percent sign and click Formatting to view the Display Format dialog box. Select an appropriate display formatting option from the Display Format drop-down menu.

9. To add a new line, place the cursor where you want the break and then click Insert New Line. You also can use Ctrl+Enter to insert a new line wherever the cursor is located. (Only body messages support multiple lines.)
10. Click OK to save the string.

Notification Message Example

The following message uses both static and dynamic text:

The resulting notification would be as shown below. The dynamic text is shown in bold.

Notification Token Categories

The Edit <item> token chooser categorizes the tokens into logical groupings for ease of lookup. The two GNS specific categories are Notification Current Values and Notification Timeout. See Token Categories in the CygNet Studio section for more information.

Notification Configurable Bit Tokens

The following tokens in the Notification Current Values category can be used to identify the alarm to which a notification maps.

• Notification Configurable Bit Name (%cfgbitactivename%)
• Notification Configurable Bit Calc Parm 1 (%cfgbitactivecalcparm1%)
• Notification Configurable Bit Calc Parm 1 Description (%cfgbitactivecalcparm1desc%)
• Notification Configurable Bit Calc Parm 2 (%cfgbitactivecalcparm2%)
• Notification Configurable Bit Calc Parm 2 Description (%cfgbitactivecalcparm2desc%)

You can include these tokens in a Set or Clear message (or email subject) to identify the name and description of the configurable bit for the point state that initiated the specific notification. The Notification Configurable Bit tokens are relative to the configurable bit that is causing the alarm to occur.

For example, you could configure the following notification message for any limit alarm or warning, without knowing the specific configurable bit number, its designated name, or the current limit configured:

If the notification was triggered because Battery Voltage on Well-1234 fell below the configurable Low Warning value of 3.5, the resulting notification message would read as follows:

Conveniently, the same formatted message string works without modification if, for instance, the notification was triggered because Tank Level on Tank-789 rose above the configurable High Alarm value of 20 feet. In this case, the resulting notification message would read as follows:

WAV File Example

You use Facility Table 3 in the FAC service to describe the area in which a remote device resides. The entries are Area1, Area2, and Area3. You also have WAV files for each area that are named Area1.wav, Area2.wav, and Area3.wav. When an alarm occurs in a particular area, you want to play that area’s WAV file. In the Wave Msg field in the GNS, you can enter %facility_table3%.wav, for example:

When an alarm occurs in Area1, the WAV file name would be substituted with Area1.wav.

Beware of Typographical Errors

If you have a typographical error in a token, the resulting text will include the typo. If you use %Desc% instead of %Description%, the message will include %Desc% as shown below, since %Desc% is not a valid token.

More:

Including Other Points in Notifications